home *** CD-ROM | disk | FTP | other *** search
/ Computer Music Interactif…cial Edition 1999 Winter / cd 3.iso / mac / Mac / Shares / Midishare™1.68 / Development Tools / Libraries / MidiFiles / MIDIFilesLib.txt < prev    next >
Encoding:
Text File  |  1995-05-17  |  11.5 KB  |  410 lines  |  [TEXT/MSWD]

  1.  
  2.  
  3.  
  4. MidiShare Functions Library
  5.  
  6.  
  7. MIDI Files Management
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15. GRAME Research Lab.
  16. 6 quai Jean Moulin - BP 1185
  17. 69202 LYON CEDEX 01
  18. Ph: (33) 72.07.37.00 Fax: (33) 72.07.37.01
  19.  
  20. e-mail : GRAME@rd.grame.fr
  21.  
  22.  
  23.  
  24.  
  25.  
  26. Functions Summary
  27.  
  28.  
  29. MidiFileGetVersion    return the version numbers
  30.  
  31. MidiFileOpen     open an existing MIDI file
  32. MidiFileClose    close a file opened with MidiFileOpen
  33. MidiFileCreate    create a MIDI file
  34.  
  35. MidiFileOpenTrack     open an existing track
  36. MidiFileNewTrack    create a new track
  37. MidiFileCloseTrack    close a track
  38. MidiFileSetPos    locate to the beginning of a track
  39.  
  40. MidiFileReadEv    read an event within the current track
  41. MidiFileReadTrack     read a track
  42.  
  43. MidiFileWriteEv     write an event to the current track
  44. MidiFileWriteTrack    write a sequence to a track
  45.  
  46.  
  47.  
  48.  
  49. Warning: all these functions doesn't check for datas consistency,  
  50. according to the MIDIFile specifications. 
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. MidiFileChooseTrack
  59. Function
  60. Synopsis
  61. #include <MidiFile.h>
  62. Boolean MidiFileChooseTrack( midiFILE *fd, short numTrack);
  63.  
  64. Description
  65. Locate at the beginning of the track numTrack within the file pointed to by fd.
  66. An error occur if the function returns false:
  67.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  68.     otherwise, the error code is in errno.
  69.  
  70.  
  71.  
  72. MidiFileClose
  73. Function
  74. Synopsis
  75. #include <MidiFile.h>
  76. Boolean MidiFileClose( midiFILE *fd);
  77.  
  78. Description
  79. Close the file pointed to by fd, previously opened with MidiFileOpen or MidiFileCreate. 
  80. If a track is still opened, the function closes it with a call to MidiFileCloseTrack.
  81.  
  82. see also : MidiFileOpen MidiFileCreate
  83.  
  84.  
  85.  
  86. MidiFileCloseTrack
  87. Function
  88. Synopsis
  89. #include <MidiFile.h>
  90. Boolean   MidiFileCloseTrack( midiFILE *fd);
  91.  
  92. Description
  93. Close a track previously opened with MidiFileOpenTrack or created with MidiFileNewTrack. 
  94. - If the file is opened for reading, MidiFileCloseTrack locate the file pointeur at the 
  95.   beginning of the next track.
  96. - If the file is opened for writing, MidiFileCloseTrack flush the KeyOff sequence (coming 
  97.   from typeNote events), update the track header and the file header.
  98. The function does nothing and returns true if the track is still closed.
  99.  
  100. An error occur if the function returns false:
  101.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  102.     otherwise, the error code is in errno.
  103.  
  104. see also : MidiFileOpenTrack MidiFileNewTrack
  105.  
  106.  
  107.  
  108.  
  109. MidiFileCreate
  110. Function
  111. Synopsis
  112. #include <MidiFile.h>
  113. midiFILE *MidiFileCreate( const char *filename, short format, short timeDef, short ticks);
  114.  
  115. Description
  116. Create a MIDIFile format file. The function parameters are as follow:
  117.          filename    :  name of the file to create.
  118.     format    :  MIDIFile format of the file, it can takes the following values:
  119.                  - midifile0 : format 0 (one track)
  120.                 - midifile1 : format 1 (several tracks, to read according
  121.                                  to the tempo map contained in the track #0)
  122.                  - midifile2 : format 2 (several independant patterns one per track, 
  123.                                  every track contains its own tempo map)
  124.          timeDef    : specify the time representation, it can takes the following values:
  125.                                - TicksPerQuarterNote     : MIDI measured time.
  126.                                 - Smpte24                : smpte time 24 frame/sec.
  127.                                 - Smpte25                 : smpte time 25 frame/sec.
  128.                                 - Smpte29                 : smpte time 29 frame/sec.
  129.                                 - Smpte30                 : smpte time 30 frame/sec.
  130.          ticks        : for MIDI time: represents the ticks count per quarter note.
  131.               for smpte time: represents the ticks count per frame.
  132.  
  133. The function returns a pointer to the following structure:
  134.     typedef struct midiFILE{
  135.         short     format;            /* file format                         */
  136.         unsigned short ntrks;    /* track count                       */
  137.         short    time;            /* time representation :            */
  138.                     /* for MIDI time: tick count per quarter note    */
  139.                     /* for smpte time: b. 15  = 1                     */
  140.                     /*                 b.8-14 = frame count per sec   */
  141.                     /*          b.0-7  = tick count per frame  */
  142.         FILE     *fd;            /* standard file descriptor             */    
  143.         fpos_t  trkHeadOffset;    /* track header offset                  */
  144.                                 /* nil if the track is closed           */
  145.         long    _cnt;
  146.         MidiSeqPtr keyOff;    /* keyOff coming from typeNote events   */
  147.         long     curDate;    /* current date                         */
  148.         Boolean mode;        /* 0/1 : reading/writing                */
  149.     }midiFILE;
  150.  
  151. An error occur if the function returns null:
  152.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  153.     otherwise, the error code is in errno.
  154.  
  155. see also : MidiFileOpen MidiFileClose
  156.  
  157. MidiFileGetVersion
  158. Function
  159. Synopsis
  160. #include <MidiFile.h>
  161. const MDF_versions *MidiFileGetVersion(void);
  162.  
  163. Description
  164. Return the version number of the implemented MIDIFile format and of  the source code.
  165.  
  166. MidiFileGetVersion returns a pointer on the following structure:
  167.     typedef struct MDF_versions{
  168.         short    src;                /* source code version              */
  169.         short     MidiFile;            /* MIDIFile format version          */
  170.     }MDF_versions;
  171.  
  172.  
  173. MidiFileNewTrack
  174. Function
  175. Synopsis
  176. #include <MidiFile.h>
  177. Boolean  MidiFileNewTrack( midiFILE *fd);
  178.  
  179. Description
  180. MidiFileNewTrack adds a new track header at the end of the file and open the 
  181. corresponding track. You can use this function only if the file is opened for writing. 
  182. A previously opened track will first been closed.
  183.  
  184. An error occur if the function returns false:
  185.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  186.     otherwise, the error code is in errno.
  187.  
  188. see also : MidiFileOpenTrack MidiFileCloseTrack
  189.  
  190.  
  191.  
  192. MidiFileOpen
  193. Function
  194. Synopsis
  195. #include <MidiFile.h>
  196. midiFILE *MidiFileOpen( const char *filename, short mode);
  197.  
  198. Description
  199. Open an existing MIDI file. The function parameters are as follow:
  200.          filename     :  name of the file.
  201.          mode         :  can takes the following values :
  202.                                 - MidiFileRead       : to read the file
  203.                                  - MidiFileAppend     : to append to the file
  204.  
  205. The function returns a pointer to the following structure:
  206.     typedef struct midiFILE{
  207.         short     format;            /* file format                         */
  208.         unsigned short ntrks;    /* track count                       */
  209.         short    time;            /* time representation :            */
  210.                     /* for MIDI time: tick count per quarter note    */
  211.                     /* for smpte time: b. 15  = 1                     */
  212.                     /*                 b.8-14 = frame count per sec   */
  213.                     /*          b.0-7  = tick count per frame  */
  214.         FILE     *fd;            /* standard file descriptor             */    
  215.         fpos_t  trkHeadOffset;    /* track header offset                  */
  216.                                 /* nil if the track is closed           */
  217.         long    _cnt;
  218.         MidiSeqPtr keyOff;        /* keyOff coming from typeNote events   */
  219.         long     curDate;        /* current date                         */
  220.         Boolean mode;            /* 0/1 : reading/writing                */
  221.     }midiFILE;
  222.  
  223. An error occur if the function returns nil:
  224.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  225.     otherwise, the error code is in errno.
  226.  
  227. see also : MidiFileClose MidiFileCreate
  228.  
  229.  
  230.  
  231.  
  232.  
  233. MidiFileOpenTrack
  234. Function
  235. Synopsis
  236. #include <MidiFile.h>
  237. Boolean  MidiFileOpenTrack( midiFILE *fd);
  238.  
  239. Description
  240. Open the track if the file is opened for reading, otherwise the function returns 
  241. false and MidiFile_errno is set to MidiFileErrNoTrack.  The function does nothing 
  242. and returns true if the track is still opened. The purpose of this function consists 
  243. essentially in data initialization to facilitate the track handling.
  244.  
  245. see also : MidiFileNewTrack MidiFileCloseTrack
  246.  
  247.  
  248.  
  249. MidiFileReadEv
  250. Function
  251. Synopsis
  252. #include <MidiFile.h>
  253. MidiEvPtr  MidiFileReadEv( midiFILE *fd);
  254.  
  255. Description
  256. MidiFileReadEv returns the next event within the current track. The track must be 
  257. opened using MidiFileOpenTrack before reading an event. When you reach the end of the 
  258. current track, it is automaticaly closed and the function returns nil.
  259.  
  260. An error occur if the function returns nil when the track is still opened:
  261.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  262.     otherwise, the error code is in errno.
  263.  
  264. see also : MidiFileReadTrack isTrackOpen
  265.  
  266.  
  267.  
  268. MidiFileReadTrack
  269. Function
  270. Synopsis
  271. #include <MidiFile.h>
  272. MidiSeqPtr MidiFileReadTrack( midiFILE *fd);
  273.  
  274. Description
  275. The function reads the current track from the file and returns the result in a MidiShare 
  276. sequence. MidiFileReadTrack automaticaly opens and closes the track to read.
  277.  
  278. An error occur if the function returns nil when the track is still opened:
  279.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  280.     otherwise, the error code is in errno.
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289. MidiFileWriteEv
  290. Function
  291. Synopsis
  292. #include <MidiFile.h>
  293. Boolean    MidiFileWriteEv( midiFILE *fd, MidiEvPtr ev);
  294.  
  295. Description
  296. MidiFileWriteEv writes the event ev to the current track. The track must be previously 
  297. opened using the MidiFileNewTrack function.
  298.  
  299. An error occur if the function returns false:
  300.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  301.     otherwise, the error code is in errno.
  302.  
  303. see also : MidiFileWriteTrack
  304.  
  305.  
  306.  
  307. MidiFileWriteTrack
  308. Function
  309. Synopsis
  310. #include <MidiFile.h>
  311. Boolean MidiFileWriteTrack( midiFILE *fd, MidiSeqPtr seq);
  312.  
  313. Description
  314. Writes in order all the events of the sequence seq to the file pointed to by fd. 
  315. MidiFileWriteTrack automaticaly create and close the written track. 
  316.  
  317. An error occur if the function returns false:
  318.     it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  319.     otherwise, the error code is in errno.
  320.  
  321. see also : MidiFileWriteEv
  322.  
  323.  
  324.  
  325. isTrackOpen
  326. macro
  327.  
  328. #include <MidiFile.h>
  329.  
  330. #ifdef __cplusplus
  331.     inline Boolean isTrackOpen( midiFILE *fd) 
  332.                         { return (fd->trkHeadOffset> 0) }
  333. #else
  334.     #define isTrackOpen(fd)    (fd->trkHeadOffset > 0)
  335. #endif
  336.  
  337. Description
  338. Returns the current track state: closed or opened.
  339.  
  340.  
  341.  
  342.  
  343. Source code examples
  344.  
  345. A typical example of code to read a MIDI file might be the following one:
  346.  
  347. MidiSeqPtr ReadMIDIFile( char *itsName)
  348. {
  349.     MidiSeqPtr seq, tmp;
  350.     midiFILE *fd;
  351.     unsigned short n;
  352.     
  353.     seq= MidiNewSeq()                /* allocate a new MidiShare sequence */
  354.     if( fd= MidiFileOpen( itsName, MidiFileRead))
  355.     {
  356.         n= fd->ntrks;                /* get the number of tracks     */
  357.         while( n--) {
  358.             tmp= MidiFileReadTrack( fd);    /* read every track        */
  359.  
  360.             Mix( tmp, seq);            /* the Mix function is to provide*/
  361.                                     /* it transfers the content of the first    */
  362.                                     /* sequence to the second one,         */
  363.                                     /* its interface might be :        */
  364.                                     /* void Mix( MidiSeqPtr src, MidiSeqPtr dst)*/
  365.  
  366.             MidiFreeSeq( tmp);    /* this sequence is now empty, we can    */
  367.                                 /* free it without freing the readed    */
  368.                                 /* events                */
  369.         }
  370.         MidiFileClose( fd);
  371.     }
  372.     return seq;
  373. }
  374.  
  375.  
  376.  A typical example of code to create a format 1 MIDI file might be the following one:
  377.  
  378. void WriteMIDIFile( char *itsName)
  379. {
  380.     midiFILE *fd;
  381.  
  382.     /* we first create a new MIDI file using a format 1    */
  383.     if( fd= MidiFileCreate( itsName, midifile1, TicksPerQuarterNote, 500))
  384.     {
  385.         /* for the file consistency, the first track     */
  386.         /* to write is the tempo map            */                
  387.         MidiFileWriteTrack( fd, myTempoMap);
  388.  
  389.         /* then we can write all the other tracks    */
  390.                     /* 
  391.                        it is the program responsibility to determine 
  392.                        the content of the tracks. Here, every track is
  393.                        stored in separate MidiShare sequences (myTempoMap,
  394.                        track1, track2,...trackn). They are supposed to be
  395.                        global variables. Of course, events in the file will
  396.                        keep exactly the same order than in the sequence
  397.                      */
  398.         MidiFileWriteTrack( fd, track1);
  399.         MidiFileWriteTrack( fd, track2);
  400.         /* ...*/
  401.         MidiFileWriteTrack( fd, trackn);
  402.         
  403.         /* and we finaly close the file            */
  404.         MidiFileClose( fd);
  405.     }
  406. }
  407.  
  408. Warning! take care of that these examples doesn't check for errors
  409.  
  410.